Guide to Cog Basics - Player Functions and Using Arrays

Any good level requires fun and innovative cogs. Cog is the basis of special of effects in JediKnight and in this article we are going to discuss 2 of the basic functions/principles that every good cog writer should know and understand.

Part 1: The player

Whether you are cogging for Multiplayer or Singleplayer, it is likely that eventually you will want to do something with Kyle, or one of his Multiplayer counterparts. To do this in cog, we must first figure out who he is. In Singleplayer ( or a Multiplayer local cog ) this is east to achieve with the 

GetLocalPlayerThing(); 

function. This function does exactly what it says, it gets the thing value of the Local Player in the game (I like to call it the ID).  This is how we use this function:

player = GetLocalPlayerThing();     

player is declared as a thing in the symbols section. 

Once you have the players thing number stored in your cog, the rest is pretty straightforward. Lets say, for example that we want to change the players model (referenced as model in the symbols section of the cog. Example: model  mymdl=ky.3do) from neutral to red (as done in CTF). This would be impossible to achieve without knowing the players ID. 

player = GetLocalPlayerThing();
SetThingModel(player,newmodel);

This is a very basic demonstration of how powerful the players ID can be.

GetLocalPlayerThing(); is the most basic of the player functions. Imagine that you want to find out who pushed a switch. Well this would require getting the sender from the switch. Assuming that you have a switch set up in a script already, this function would get the switch pusher for you:

Activated:
player = GetSenderRef();

Again, player is a thing.

This function is much like the first, except it simply picks up who executed a certain aspect within the level. To add on our model example, lets change the model of someone who pushes a switch:

Activated:
player = GetSenderRef();
SetThingModel(player,newmodel);

As you can see, the player is being determined when the switch is being pushed. This is a very important concept to grasp for Multiplayer cog scripting. 
	Another use of GetSenderRef(); is to find out who or what was killed. This is very simple to do, and can aide in scoring measures.

killed:
player = GetSenderRef();

With that one function you can determine who died, and do what you please with the dead person. Now you are wondering, who killed the dead player? Good Question, this is what the next function handles. It is a bit more complicated than the first two, but just as powerful:

killed:
SourceRef = GetSourceRef();  
player = GetThingParent(SourceRef);

you can also combine these two functions into one:

killed:
player = GetThingParent(GetSourceRef());

The GetThingParent(); function simply gets the owner of the weapon that killed the person. For example, the parent of a rail charge that got fired is whoever shot it. Now it is time to change our example around again. This time, lets set the model of the dead person to a new one, and set the model of a killer to a new model as well.

killed:
player = GetSenderRef();
SetThingModel(player,deadmodel);
killer = GetThingParent(GetSourceRef());
SetThingModel(killer,killermodel);

Killer is a thing reference just as Player is. That sums up the basics of understanding three very important functions about the player, with these functions mastered, you can pretty much do anything you like with the player in JediKnight.


Part 2: Using Arrays in COG:

An array is a very powerful tool within cog. It can save the author many lines of code when repeating a function for many things. If you are not familiar with arrays, they are simply a tool that, when used with a FOR loop, can save you a lot of typing. In this example cog script, we will set the sector thrust for a number of sectors:

symbols
message startup
vector   vec
int       speed=5
int index=0  local		desc=Index
int numsec=0 local		desc=Number_of_Sectors
sector sec0
sector sec1
sector sec2
sector sec3
sector sec4
sector sec5
sector sec6 
sector sec7
sector sec8 
sector sec9 
sector sec10
sector sec11
sector sec12
sector sec13
sector sec14
end
code
startup:
		// the below lines simply count the number of sectors in use for us
			if(sec0 >= 0) numsec = numsec + 1;
			if(sec1 >= 0) numsec = numsec + 1;
			if(sec2 >= 0) numsec = numsec + 1;
			if(sec3 >= 0) numsec = numsec + 1;
			if(sec4 >= 0) numsec = numsec + 1;
			if(sec5 >= 0) numsec = numsec + 1;
			if(sec6 >= 0) numsec = numsec + 1;
			if(sec7 >= 0) numsec = numsec + 1;
			if(sec8 >= 0) numsec = numsec + 1;
			if(sec9 >= 0) numsec = numsec + 1;
			if(sec10 >= 0) numsec = numsec + 1;
			if(sec11 >= 0) numsec = numsec + 1;
			if(sec12 >= 0) numsec = numsec + 1;
			if(sec13 >= 0) numsec = numsec + 1; 		
if(sec14 >= 0) numsec = numsec + 1;
	
		// this loop will carry out a function for every sector.
	
			for (index=0; index < numsec; index = index + 1)
		{

		SetSectorThrust(sec0[index], vec, speed);

		}
		Return;
end


The if statements are there to count how many sectors we have in use. The for loop does the grunt work here. The first parameter starts index at 0, and adds 1 to itself as long as it is less than numsec. To guarantee a working for loop, your sector references must be sequential in the symbols section. This is done in the above cog by naming them sec0 - sec14. As you can see, the array is a very powerful tool and is not that tough of a concept to understand.

The two aspects of cog that we covered today are very important for any good scripter, learn them, and your cogs will become more and more complex.

Thanks to Tom Smallwood for assistance on the array concept.





